package com.smart.community.user.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.user.entity.UserUploadFile;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;

/**
 * 用户上传文件服务接口
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 1.0.0
 */
public interface UserUploadFileService extends IService<UserUploadFile> {

    /**
     * 上传文件
     * 
     * @param file 文件
     * @param userId 用户ID
     * @param uploadType 上传类型
     * @param uploadSource 上传来源
     * @return 文件信息
     * @throws Exception 统一异常
     */
    UserUploadFile uploadFile(MultipartFile file, Long userId, String uploadType, String uploadSource) throws Exception;

    /**
     * 根据用户ID查询文件列表
     * 
     * @param userId 用户ID
     * @return 文件列表
     * @throws Exception 统一异常
     */
    List<UserUploadFile> getFilesByUserId(Long userId) throws Exception;

    /**
     * 根据用户ID和上传类型查询文件列表
     * 
     * @param userId 用户ID
     * @param uploadType 上传类型
     * @return 文件列表
     * @throws Exception 统一异常
     */
    List<UserUploadFile> getFilesByUserIdAndType(Long userId, String uploadType) throws Exception;

    /**
     * 删除文件
     * 
     * @param fileId 文件ID
     * @param userId 用户ID
     * @return 删除结果
     * @throws Exception 统一异常
     */
    boolean deleteFile(Long fileId, Long userId) throws Exception;

    /**
     * 获取文件访问URL
     * 
     * @param fileId 文件ID
     * @return 文件访问URL
     * @throws Exception 统一异常
     */
    String getFileUrl(Long fileId) throws Exception;

    /**
     * 更新文件下载次数
     * 
     * @param fileId 文件ID
     * @throws Exception 统一异常
     */
    void updateDownloadCount(Long fileId) throws Exception;

    /**
     * 更新文件查看次数
     * 
     * @param fileId 文件ID
     * @throws Exception 统一异常
     */
    void updateViewCount(Long fileId) throws Exception;

    /**
     * 清理过期文件
     * 
     * @throws Exception 统一异常
     */
    void cleanExpiredFiles() throws Exception;

    /**
     * 验证文件大小
     * 
     * @param file 文件
     * @param maxSize 最大大小（字节）
     * @throws Exception 统一异常
     */
    void validateFileSize(MultipartFile file, Long maxSize) throws Exception;

    /**
     * 验证文件类型
     * 
     * @param file 文件
     * @param allowedTypes 允许的文件类型
     * @throws Exception 统一异常
     */
    void validateFileType(MultipartFile file, String[] allowedTypes) throws Exception;


} 